home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Libraries / PatchLib 1.0d3 / Documentation / README < prev    next >
Encoding:
Text File  |  1994-12-01  |  4.0 KB  |  136 lines  |  [TEXT/KAHL]
  1. ===========
  2. Description
  3. -----------
  4.  
  5. Patch Library is used to manage patches to traps. Installing and removing
  6. patches is simpler than using the Toolbox routines NSetTrapAddress and
  7. NGetTrapAddress. In addition, macros are provided that setup and restore
  8. the environment for the patch routine. Patch Library is not as useful
  9. for native PowerPC software as it is for 68K software, and for software
  10. that must avoid tail patches. Complete C source code and a THINK C 7.0
  11. project are provided.
  12.  
  13. (c) Copyright 1994 Ari Halberstadt. See the file Distribution for
  14. distribution terms.
  15.  
  16. ============================
  17. What is in this Distribution
  18. ----------------------------
  19.  
  20. :Documentation:Distribution
  21.     Distribution policy, copyright notice, my address
  22.  
  23. :Documentation:README
  24.     This document
  25.     
  26. :Documentation:Version History
  27.     Documents the changes made to each version of Patch Library
  28.  
  29. :Executables:
  30.     Contains an executable M68K binary for testing the patch
  31.     library.
  32.  
  33. :Source:PatchLib
  34.     Folder containing the source code for Patch Library
  35.  
  36. :Source:PatchTest
  37.     Folder containing the source code for a simple application
  38.     that demonstrates Patch Library.
  39.  
  40. ===================
  41. Using Patch Library
  42. -------------------
  43.  
  44. Patch Library is used to manage patches to traps. You can create as many
  45. patches as you like. Each patch is created as a non-relocatable block in
  46. the heap. Under Finder (but not MultiFinder) you must remove all patches
  47. before exiting the application. All patches are tracked in a linked-list
  48. of patches, so that you can easily remove all of the patches when
  49. exiting.
  50.  
  51. The patch function must be declared with the same prototype as the
  52. trap that it is patching. The parameters that are passed to the function
  53. are the same parameters on the stack that were passed in the call to
  54. the trap. This allows you to change the values of the parameters before
  55. you call the original trap routine. You should call PATCH_ENTER at the
  56. start of your patch function, and call PATCH_RETURN at the end of your
  57. patch function. The PATCH_ENTER macro saves registers d0-d7/a0-a7 and
  58. sets up register a5. The PATCH_RETURN macro restores all saved registers
  59. and calls the address of the original trap routine. Both macros are no-ops
  60. in PowerPC code.
  61.  
  62. You can temporarily remove the patch with PatchRemove and reinstall it with
  63. PatchInstall. To permanently remove the patch and dispose of the memory it
  64. occupies call PatchEnd.
  65.  
  66. This library is meant to be used with an application. It could be modified
  67. to work with a system extension, but you would have to allocate the
  68. patches with NewPtrSysClear instead of NewPtrClear. Additional changes
  69. might also be needed.
  70.  
  71. ====================
  72. Functional Interface
  73. --------------------
  74.  
  75.     void PatchInstall(PatchType patch)
  76.  
  77. * PatchInstall installs a patch.
  78.  
  79.     void PatchRemove(PatchType patch)
  80.  
  81. * PatchRemove removes a patch.
  82.  
  83.     void PatchRemoveAll(void)
  84.  
  85. * PatchRemoveAll removes all patches.
  86.  
  87.     PatchType PatchBegin(void *addr, short num)
  88.  
  89. * PatchBegin creates and installs a patch, and returns a pointer to the
  90. patch structure, or NULL if the patch could not be created.
  91.  
  92.     void PatchEnd(PatchType patch)
  93.  
  94. * PatchEnd removes and disposes of the patch.
  95.  
  96.     void PatchEndAll(void)
  97.  
  98. * PatchEndAll removes and disposes of all patches.
  99.  
  100. ========
  101. EXAMPLES
  102. --------
  103.  
  104. See the file PatchTest.c for a simple, yet complete, example of how
  105. to use Patch Library.
  106.  
  107. ========================
  108. Native (and Fat) Patches
  109. ------------------------
  110.  
  111. Patch Library is primarily useful for writing non-native trap patches.
  112. You should generally use fat code (M68K and PPC) for all of your
  113. patches. I have not yet written a fat patch. You should not patch
  114. selector-based routines since Apple provides no documented method
  115. for doing so using PPC patches. 
  116.  
  117. =======
  118. PORTING
  119. -------
  120.  
  121. This library was developed using THINK C 5.0.4 and 7.0. The C code should be
  122. portable to other compilers, and has been used successfully compiled with
  123. CodeWarrior DR4.
  124.  
  125. ==============
  126. Known Problems
  127. --------------
  128.  
  129. There are no known problems.
  130.  
  131. =======
  132. Credits
  133. -------
  134.  
  135. Suggest something and have your name placed here! :-)
  136.